/*
* ============================================================================
*  Name        : cameraengine.h
*  Part of     : Symbian/S60 Camera Wrapper
*  Description : Camera engine class declaration
*  Version     : %version: 2 %
*
* This program is free software. It comes without any warranty, to
* the extent permitted by applicable law. You can redistribute it
* and/or modify it under the terms of the Do What The Fuck You Want
* To Public License, Version 2, as published by Sam Hocevar. See
* http://sam.zoy.org/wtfpl/COPYING for more details.
*
* You are welcome to, but not required to, contribute any modifications that
* improve stability, usability and/or feature set of the library back to
* Symbian/S60 Camera Wrapper project, as long as binary compatibility is
* retained. See https://projects.forum.nokia.com/camerawrapper for more info.
* ============================================================================
*/

/** @file cameraengine.h */

#ifndef CCAMERAENGINE_H
#define CCAMERAENGINE_H

// INCLUDES
#include <e32base.h>
#include <ecam.h>

// FORWARD DECLARATIONS
class CCameraEnginePrivate;
class MCameraEngineObserver;
class CCameraAdvancedSettings;

#ifdef DOXYGEN
#define NONSHARABLE_CLASS(X) class X
#endif

/** @class CCameraEngine
  * @brief Camera engine class.
  */
NONSHARABLE_CLASS( CCameraEngine ) : public CBase
  {
public:

  /**
   * @enum TCameraEngineState
   * @brief Enumeration for possible camera engine states.
   */
  enum TCameraEngineState
      {
      EEngineNotReady,
      EEngineIdle,
      EEngineViewFinding,
      EEngineCapturing,
      EEngineFocusing
      };

  /**
   * Constructs a new camera engine instance.
   * @param aCameraHandle Handle (index) to a camera.
   * @see CamerasAvailable().
   * @param aPriority Value from -100 to 100 indicating relative 
   * priority of client to use camera. Ignored if the client does
   * not have MultimediaDD capability.
   * @param aObserver Pointer to class derived from MCameraEngineObserver
   * designed to receive notifications of asynchronous event completion.
   * @return CCameraEngine The new camera engine instance.
   * @leave May leave with one of the system-wide error codes.
   */
  IMPORT_C static CCameraEngine* NewL( TInt aCameraHandle, 
                                       TInt aPriority, 
                                       MCameraEngineObserver* aObserver );
  /**
   * Destructor. Stops the viewfinder and releases all resources.
   */                              
  IMPORT_C ~CCameraEngine();
  
public:

  /**
   * Returns the current state of the camera engine.
   */
  IMPORT_C TCameraEngineState State() const;

  /**
   * Returns true if the camera has been reserved and
   * powered on.
   */
  IMPORT_C TBool IsCameraReady() const;

  /**
   * Returns true if the camera supports AutoFocus.
   */
  IMPORT_C TBool IsAutoFocusSupported() const;
  
  /**
   * Captures an image. When complete, observer will receive
   * MceoCapturedDataReady() or MceoCapturedBitmapReady() callback,
   * depending on which image format was used in PrepareL().
   * @leave May leave with KErrNotReady if camera is not
   * reserved or prepared for capture.
   */
  IMPORT_C void CaptureL();
  
  /**
   * Reserves and powers on the camera. When complete,
   * observer will receive MceoCameraReady() callback
   *
   */
  IMPORT_C void ReserveAndPowerOn();

  /**
   * Releases and powers off the camera
   *
   */
  IMPORT_C void ReleaseAndPowerOff();

  /**
   * Prepares for image capture.
   * @param aCaptureSize requested capture size. On return,
   * contains the selected size (closest match)
   * @param aFormat Image format to use. Default is JPEG with
   * EXIF information as provided by the camera module
   * @leave Possible leave codes: KErrNotSupported, KErrNoMemory,
   * KErrNotReady
   */
  IMPORT_C void PrepareL( TSize& aCaptureSize,               
      CCamera::TFormat aFormat = CCamera::EFormatExif );
      
  /**
   * Starts the viewfinder. Observer will receive 
   * MceoViewFinderFrameReady() callbacks periodically.
   * @param aSize requested viewfinder size. On return,
   * contains the selected size.
   * 
   * @leave KErrNotSupported if viewfinding with bitmaps is not
   * supported, KErrNotReady 
   */
  IMPORT_C void StartViewFinderL( TSize& aSize );

  /**
   * Stops the viewfinder if active.
   */
  IMPORT_C void StopViewFinder();
  
  /**
   * Releases memory for the last received viewfinder frame.
   * Client must call this in response to MceoViewFinderFrameReady()
   * callback, after drawing the viewfinder frame is complete.
   */
  IMPORT_C void ReleaseViewFinderBuffer();
  
  /**
   * Releases memory for the last captured image.
   * Client must call this in response to MceoCapturedDataReady()
   * or MceoCapturedBitmapReady()callback, after processing the 
   * data/bitmap is complete.
   */
  IMPORT_C void ReleaseImageBuffer();
  
  /**
   * Starts focusing. Does nothing if AutoFocus is not supported.
   * When complete, observer will receive MceoFocusComplete()
   * callback.
   * @leave KErrInUse, KErrNotReady
   */
  IMPORT_C void StartFocusL();
  
  /**
   * Cancels the ongoing focusing operation.
   */
  IMPORT_C void FocusCancel();

  /**
   * Returns a bitfield of supported focus ranges.
   * @param aSupportedRanges On return, contains a bitfield of either
   * TAutoFocusRange (S60 3.0/3.1 devices) or TFocusRange 
   * (S60 3.2 and onwards) values.
   * @note Interpret the returned values as a bitfield of TFocusRange
   * values if AdvancedSettings() is not NULL, otherwise as 
   * TAutoFocusRange.
   */
  IMPORT_C void SupportedFocusRanges( TInt& aSupportedRanges ) const;
  
  /**
   * Sets the focus range
   * @param aFocusRange one of the values returned by
   * SupportedFocusRanges().
   */
  IMPORT_C void SetFocusRange( TInt aFocusRange );
  
  /**
   * Returns a pointer to CCamera object used by the engine.
   * Allows getting access to additional functionality
   * from CCamera.
   * @note Do not use for functionality already provided
   * by other CCameraEngine methods!
   */
  IMPORT_C CCamera* Camera();
  
  /**
   * Returns a pointer to CCameraAdvancedSettings object used by 
   * the engine. May be NULL if adv. settings is not available.
   * Allows getting access to additional functionality
   * from CCameraAdvancedSettings.
   * @note Do not use for functionality already provided
   * by other CCameraEngine methods!
   */
  IMPORT_C CCamera::CCameraAdvancedSettings* AdvancedSettings();
  
  /**
   * Static function that returns the number of cameras on the device.
   * @return TInt Number of cameras available on the device. Typically,
   * the first (index 0) is the main camera, and the second, if 
   * available, is the front-facing camera.
   */
  IMPORT_C static TInt CamerasAvailable();
  
  /**
   * Maximum digital zoom value. 0 if digital zoom is not supported.
   * @return TInt Maximum value supported by the digital zoom.
   */
  IMPORT_C TInt MaxDigitalZoom();
  
  /**
   * Returns the current digital zoom value.
   * @return TInt Current digital zoom value.
   */
  IMPORT_C TInt DigitalZoom();
  
  /**
   * Adjusts digital zoom.
   * @param aTele Set to ETrue to increase zoom (tele) or EFalse to
   * decrease zoom (wide).
   * @return TInt Returns the new digital zoom level, or KErrNotSupported.
   */
  IMPORT_C TInt AdjustDigitalZoom( TBool aTele );
  
  /**
   * Returns a bitfield of supported exposure modes.
   * @see CCamera::TExposure.
   * 
   */
  IMPORT_C TInt SupportedExposureModes();
  
  /**
   * Returns the current exposure mode.
   * @see CCamera::TExposure.
   */
  IMPORT_C TInt Exposure();
  
  /**
   * Set camera exposure mode.
   * @param aExposure One of the modes returned by SupportedExposureModes().
   * @return KErrNone or KErrNotSupported.
   * @see CCamera::TExposure.
   */
  IMPORT_C TInt SetExposure( TInt aExposure );

  /**
   * Returns a bitfield of supported flash modes.
   * @see CCamera::TFlash.
   */
  IMPORT_C TInt SupportedFlashModes();
  
  /**
   * Returns the current flash mode.
   * @see CCamera::TFlash.
   */
  IMPORT_C TInt Flash();

  /**
   * Set camera flash mode.
   * @param aFlash One of the modes from SupportedFlashModes.
   * @return KErrNone or KErrNotSupported.
   * @see CCamera::TFlash.
   */
  IMPORT_C TInt SetFlash( TInt aFlash );

protected:
    CCameraEngine();

private:
    CCameraEnginePrivate* iPimpl;
  };

#endif //CCAMERAENGINE_H
